
## Introduction

Even well-written methods become hard to maintain when files and projects are organized inconsistently.

This post covers practical structure rules for teams.

## 1) Organize class members consistently

A common order:

1. constants / static readonly fields
2. private fields
3. constructors
4. public properties
5. public methods
6. private methods

Consistency reduces navigation time and review friction.

## 2) Keep related logic close together

Private helper methods should appear near the public method that uses them.

Avoid scattering related logic across long files.

## 3) One class per file (most of the time)

Use file names that match class names.

- `OrderService.cs` -> `OrderService`
- `OrderNotFoundException.cs` -> `OrderNotFoundException`

Exception: tiny related types such as a request record near a small service.

## 4) Avoid overusing regions

If a class requires many `#region` blocks to be readable, the class is likely too large.

Refactor by extracting smaller cohesive classes.

## 5) Keep project boundaries clear

A clean architecture baseline:

- Domain: entities, value objects, domain rules
- Application: use cases, DTOs, interfaces, validators
- Infrastructure: databases, external APIs, file storage
- WebApi: controllers, middleware, composition root

This separation makes ownership and dependencies explicit.

## 6) Comments: explain why, not what

### Bad comment

```csharp
// Check if user is admin
if (user.Role == Role.Admin)
{
    // ...
}
```

### Better code and better comment style

```csharp
if (user.IsAdmin)
{
    // Discount capped at 30% due to compliance policy REG-2024-117
    discount = Math.Min(discount, 0.30m);
}
```

Comment only when context or business rule is not obvious.

## 7) Document public APIs with XML comments

```csharp
/// <summary>
/// Retrieves an order by its unique identifier.
/// </summary>
/// <param name="id">The order ID.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The order, or null if not found.</returns>
public Task<Order?> GetByIdAsync(int id, CancellationToken ct);
```

## 8) Delete commented-out code

Version control already preserves history. Dead commented blocks make files noisy and misleading.

## Summary

Code organization and documentation are force multipliers. Clear structure plus intentional comments makes large C# codebases easier to evolve safely.


Organize C# projects and classes for maintainability, and write comments that explain why instead of what.

C# Clean Code


## Introduction

Production code fails. Clean code does not pretend failures do not exist; it handles them explicitly and consistently.

## 1) Use exceptions correctly

### Do not use exceptions for normal control flow

```csharp
// BAD
public int Parse(string input)
{
    try { return int.Parse(input); }
    catch { return -1; }
}

// GOOD
public int? Parse(string input)
    => int.TryParse(input, out var result) ? result : null;
```

### Throw specific exceptions

```csharp
public class OrderNotFoundException(int orderId)
    : Exception($"Order with ID {orderId} was not found.")
{
    public int OrderId { get; } = orderId;
}
```

Specific exception types improve logging, diagnosis, and mapping to HTTP responses.

## 2) Never swallow exceptions silently

```csharp
try
{
    await ProcessOrderAsync(orderId, ct);
}
catch (Exception ex)
{
    _logger.LogError(ex, "Failed to process order {OrderId}", orderId);
    throw;
}
```

If you catch, either:

- recover meaningfully, or
- enrich and rethrow

## 3) Standardize API errors with ProblemDetails

```csharp
public class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext context,
        Exception exception,
        CancellationToken ct)
    {
        logger.LogError(exception, "Unhandled exception");

        var details = new ProblemDetails
        {
            Status = StatusCodes.Status500InternalServerError,
            Title = "An unexpected error occurred",
            Type = "https://tools.ietf.org/html/rfc9110#section-15.6.1"
        };

        context.Response.StatusCode = details.Status.Value;
        await context.Response.WriteAsJsonAsync(details, ct);
        return true;
    }
}
```

A consistent response structure helps API clients and monitoring tools.

## 4) Validate input at boundaries

Boundary validation keeps invalid data from leaking deep into the domain.

### API request validation (FluentValidation)

```csharp
public class CreateOrderRequestValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderRequestValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(i => i.Quantity).GreaterThan(0);
            item.RuleFor(i => i.Price).GreaterThan(0);
        });
    }
}
```

### Guard clauses inside services/domain

```csharp
public class OrderService(IOrderRepository repository)
{
    public async Task<Order> GetByIdAsync(int id, CancellationToken ct)
    {
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(id);

        return await repository.GetByIdAsync(id, ct)
            ?? throw new OrderNotFoundException(id);
    }
}
```

## 5) Prefer immutability for safety

```csharp
public record OrderDto(int Id, string CustomerName, decimal Total, DateTime CreatedAt);

public readonly record struct OrderId(int Value);
public readonly record struct CustomerId(int Value);
```

Strong types and immutable models reduce accidental state bugs.

## Summary

Reliable C# systems combine:

- clear validation boundaries
- specific exceptions
- structured error responses
- immutable and strongly-typed models

This approach makes failures understandable and recoverable.


Build resilient C# APIs with specific exceptions, ProblemDetails, validation boundaries, and immutable models.

ASP.NET Core

C# Clean Code

C# Clean Code